classdef MessageBuilder < handle
    % MESSAGEBUILDER 消息构建器
    % 用于累积和管理多条消息
    %
    % 功能：
    %   - 累积多条消息
    %   - 自动管理消息级别
    %   - 支持时间戳
    %   - 智能确定整体消息级别（最高优先级）
    %
    % 使用示例：
    %   builder = MessageBuilder();
    %   builder.add('步骤1完成', 'info');
    %   builder.add('步骤2有警告', 'warning');
    %   builder.add('步骤3成功', 'success');
    %   result = builder.build();
    %   
    %   % GUI中使用
    %   app.MessagesTextArea.Value = result.text;
    %   app.MessagesTextArea.FontColor = result.color;
    %
    % 作者: MBD Platform Team
    % 日期: 2025-10-14
    
    properties (Access = private)
        messages = {};          % 消息文本列表
        levels = {};            % 消息级别列表
        timestamps = {};        % 时间戳列表
        separator = newline;    % 分隔符
        timestampFormat = 'yyyy-MM-dd HH:mm:ss';  % 时间戳格式
        includeTimestamp = false;  % 是否包含时间戳
    end
    
    methods
        
        function obj = MessageBuilder(varargin)
            % 构造函数
            % 
            % 输入参数:
            %   varargin - 可选参数（Name-Value pairs）
            %     'Separator' - 消息分隔符（默认：newline）
            %     'TimestampFormat' - 时间戳格式（默认：'yyyy-MM-dd HH:mm:ss'）
            %     'IncludeTimestamp' - 是否包含时间戳（默认：false）
            
            % 参数解析
            p = inputParser;
            addParameter(p, 'Separator', newline, @(x) ischar(x) || isstring(x));
            addParameter(p, 'TimestampFormat', 'yyyy-MM-dd HH:mm:ss', @ischar);
            addParameter(p, 'IncludeTimestamp', false, @islogical);
            parse(p, varargin{:});
            
            obj.separator = char(p.Results.Separator);
            obj.timestampFormat = p.Results.TimestampFormat;
            obj.includeTimestamp = p.Results.IncludeTimestamp;
        end
        
        function obj = add(obj, text, level)
            % ADD 添加一条消息
            % 
            % 输入参数:
            %   text - 消息文本
            %   level - 消息级别（可选，默认：'info'）
            %
            % 示例：
            %   builder.add('操作成功');
            %   builder.add('发现警告', 'warning');
            
            if nargin < 3
                % 如果未指定级别，尝试从文本推断
                level = MessageService.inferLevel(text);
            end
            
            % 验证级别
            if ~ismember(level, {MessageService.LEVEL_INFO, ...
                                 MessageService.LEVEL_WARNING, ...
                                 MessageService.LEVEL_ERROR, ...
                                 MessageService.LEVEL_SUCCESS})
                level = MessageService.LEVEL_INFO;
            end
            
            % 添加到列表
            obj.messages{end+1} = MessageService.convertToChar(text);
            obj.levels{end+1} = level;
            obj.timestamps{end+1} = datetime('now');
        end
        
        function obj = addInfo(obj, text)
            % ADDINFO 添加信息级别消息
            obj.add(text, MessageService.LEVEL_INFO);
        end
        
        function obj = addWarning(obj, text)
            % ADDWARNING 添加警告级别消息
            obj.add(text, MessageService.LEVEL_WARNING);
        end
        
        function obj = addError(obj, text)
            % ADDERROR 添加错误级别消息
            obj.add(text, MessageService.LEVEL_ERROR);
        end
        
        function obj = addSuccess(obj, text)
            % ADDSUCCESS 添加成功级别消息
            obj.add(text, MessageService.LEVEL_SUCCESS);
        end
        
        function obj = addFromResult(obj, result)
            % ADDFROMRESULT 从Service返回的result结构添加消息
            % 
            % 输入参数:
            %   result - Service返回的结构体
            %     .success - 是否成功（boolean）
            %     .message - 消息文本（string）
            %
            % 示例：
            %   result = someService.doSomething();
            %   builder.addFromResult(result);
            
            if ~isstruct(result) || ~isfield(result, 'message')
                return;
            end
            
            % 根据success字段确定级别
            if isfield(result, 'success')
                if result.success
                    level = MessageService.LEVEL_SUCCESS;
                else
                    level = MessageService.LEVEL_ERROR;
                end
            else
                % 如果没有success字段，从消息文本推断
                level = MessageService.inferLevel(result.message);
            end
            
            obj.add(result.message, level);
        end
        
        function result = build(obj)
            % BUILD 构建最终的消息结构
            % 
            % 输出参数:
            %   result - 消息结构体
            %     .text - 合并后的消息文本
            %     .level - 整体消息级别（最高优先级）
            %     .color - RGB颜色值 [R, G, B]
            %     .messageCount - 消息数量
            %     .levelCounts - 各级别消息数量统计
            
            result = struct();
            
            % 如果没有消息
            if isempty(obj.messages)
                result.text = '';
                result.level = MessageService.LEVEL_INFO;
                result.color = MessageService.COLOR_INFO;
                result.messageCount = 0;
                result.levelCounts = struct(...
                    'info', 0, 'warning', 0, 'error', 0, 'success', 0);
                return;
            end
            
            % 构建文本
            if obj.includeTimestamp
                formattedMessages = cell(1, length(obj.messages));
                for i = 1:length(obj.messages)
                    timestampStr = char(obj.timestamps{i}, obj.timestampFormat);
                    formattedMessages{i} = sprintf('[%s] %s', ...
                        timestampStr, obj.messages{i});
                end
                result.text = strjoin(formattedMessages, obj.separator);
            else
                result.text = strjoin(obj.messages, obj.separator);
            end
            
            % 确定整体级别（优先级：error > warning > info > success）
            result.level = obj.determineOverallLevel();
            result.color = MessageService.getLevelColor(result.level);
            
            % 统计信息
            result.messageCount = length(obj.messages);
            result.levelCounts = struct(...
                'info', sum(strcmp(obj.levels, MessageService.LEVEL_INFO)), ...
                'warning', sum(strcmp(obj.levels, MessageService.LEVEL_WARNING)), ...
                'error', sum(strcmp(obj.levels, MessageService.LEVEL_ERROR)), ...
                'success', sum(strcmp(obj.levels, MessageService.LEVEL_SUCCESS)));
        end
        
        function obj = clear(obj)
            % CLEAR 清空所有消息
            obj.messages = {};
            obj.levels = {};
            obj.timestamps = {};
        end
        
        function count = count(obj)
            % COUNT 获取消息数量
            count = length(obj.messages);
        end
        
        function tf = isEmpty(obj)
            % ISEMPTY 判断是否为空
            tf = isempty(obj.messages);
        end
        
    end
    
    methods (Access = private)
        
        function level = determineOverallLevel(obj)
            % 确定整体消息级别
            % 优先级：error > warning > info/success
            
            if any(strcmp(obj.levels, MessageService.LEVEL_ERROR))
                level = MessageService.LEVEL_ERROR;
            elseif any(strcmp(obj.levels, MessageService.LEVEL_WARNING))
                level = MessageService.LEVEL_WARNING;
            elseif all(strcmp(obj.levels, MessageService.LEVEL_SUCCESS))
                % 如果全是success，则为success
                level = MessageService.LEVEL_SUCCESS;
            else
                level = MessageService.LEVEL_INFO;
            end
        end
        
    end
end

